home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 22 / AACD 22.iso / AACD / Utilities / BareED / tool / BitMapSaver.doc < prev    next >
Encoding:
Text File  |  2000-05-11  |  14.3 KB  |  448 lines
  1. BitMapSaver's doc            $VER: BitMapSaver 1.3 (06/15/96)
  2.  
  3. Author of documentation and object file: Jörg van de Loo.
  4.  
  5. Date: 06/19/93 (updated 06/15/1996)
  6.  
  7. FORMAT: BITMAPSAVER {<NAME>}TO{<NAME>}[OPT CMAP|SPRITE|C|QUICK|RAW|PEN|RAWHDR|SEPRIT|RGB32]
  8.  
  9.  
  10. FROM/A,TO/K,OPT/K/M,CMAP/S,SPRITE/S,C/S,QUICK/S,RAW/S,PEN/S,RAWHDR/S,SEPRIT/S,RGB32/S
  11.  
  12. Description:
  13.  
  14. With  this  little  program  it's possible to translate any IFF-ILBM file with
  15. less  or  equal  8 bitplanes to an assembler or C source which can be directly
  16. included.
  17.  
  18. It's  a  quite  old  tool  but one that can be used today from within a Shell-
  19. script.
  20.  
  21. ---------------------------------
  22.  
  23. C           Make code for the C-language, default assembler.
  24. SPRITE        Store data in the format needed by a SPRITE-object,
  25.         default BitMaps.
  26. PEN        Store data as 8-bit pen-array instead of BitPlanes
  27.         or sprite-object.
  28. RAW        Generate only binary data.
  29. CMAP        Store 4-bit RGB colour table, default none.
  30. RGB32        Store colour-values as V39 and up RGB32 colour format
  31.         when option CMAP was chosen, default 4-bit.
  32. SEPRIT        Split RAW-file, when option CMAP was chosen,
  33.         into image and cmap-file.
  34. RAWHDR        Write binary raw-file header instead of none if option
  35.         RAW was chosen.
  36. QUICK        Do it faster.
  37.  
  38. Example:
  39.  
  40. 4> bitmapsaver "work:dtp/pictures/gsx-r 750.iff" RAM:bike.c opt c cmap
  41.  
  42. This  will generate a file which can be used for the C-language, the data will
  43. be  stored  as  bitplanes  (each plane after another), the BitMap-structure is
  44. initialised but without pointed planes to it, the colour map is stored, too.
  45.  
  46.  
  47. ---- Generated code... ----
  48.  
  49. C-language code...
  50.  
  51. #ifndef    GRAPHICS_GFX_H
  52. #include    "graphics/gfx.h"
  53. #endif
  54.  
  55. #ifndef    EXEC_TYPES_H
  56. #include    "exec/types.h"
  57. #endif
  58.  
  59. struct BitMap NewBitMap =
  60. {
  61.     76,        /* Bytes per row */
  62.     60,        /* Height */
  63.     0,        /* Flags */
  64.     4,        /* Depth */
  65.     0,        /* Strictly for longword adjustment */
  66.     0,        /* Pointer to plane 1 */
  67.     0,        /* Pointer to plane 2 */
  68.     0,        /* Pointer to plane 3 */
  69.     0,        /* Pointer to plane 4 */
  70.     0,        /* Pointer to plane 5 */
  71.     0,        /* Pointer to plane 6 */
  72.     0,        /* Pointer to plane 7 */
  73.     0        /* Pointer to plane 8 */
  74. };
  75.  
  76.  
  77. UWORD BitMap_Data[] =  /* Important Note: You have to force the
  78.             datas on your own to chip-memory!
  79.             Also you have to set the address of
  80.             each plane to the Bitmap structure! */
  81. {
  82. /* Plane1 */
  83.  ....,
  84. /* Plane2 */
  85.  ....,
  86. /* Plane3 */
  87.  ....,
  88. /* Plane4 */
  89.  ....
  90. };
  91.  
  92. UWORD Colors[16] =
  93. {
  94. 0x0AAA,0x0000,0x0EEE,0x068B,0x0E44,0x05D5,0x004D,0x0E90,0x0F60,0x0555,
  95. 0x0FE0,0x0080,0x00D0,0x00CC,0x006F,0x000A
  96. };
  97.  
  98.  
  99. Asm-language code...
  100.  
  101. _Bitmap
  102.     dc.w    76            ; Bytes per row
  103.     dc.w    60            ; Number of lines
  104.     ds.b    1            ; Flags
  105.     dc.b    4            ; Depth
  106.     ds.w    1            ; Strictly for longword alignment
  107.     dc.l    _Plane1            ; Pointer to plane 1
  108.     dc.l    _Plane2            ; Pointer to plane 2
  109.     dc.l    _Plane3            ; Pointer to plane 3
  110.     dc.l    _Plane4            ; Pointer to plane 4
  111.     dc.l    0            ; Pointer to plane 5
  112.     dc.l    0            ; Pointer to plane 6
  113.     dc.l    0            ; Pointer to plane 7
  114.     dc.l    0            ; Pointer to plane 8
  115.  
  116.     SECTION    "BITMAP",DATA_C        ; Forced to chip memory
  117. _Plane1
  118.     dc.w ....
  119. _Plane2
  120.     dc.w ....
  121. _Plane3
  122.     dc.w ....
  123. _Plane4
  124.     dc.w ....
  125.  
  126.     SECTION    "RGBColorTable",DATA
  127. _ColorTable
  128.     dc.w    $0AAA,$0000,$0EEE,$068B,$0E44,$05D5,$004D,$0E90,$0F60,$0555
  129.     dc.w    $0FE0,$0080,$00D0,$00CC,$006F,$000A
  130.  
  131. _CMAPNumEntries
  132.     dc.w    16            ; Number of words
  133.  
  134.  
  135. The  reason why the BitPlane-pointers aren't initialised for the C-language is
  136. because  not  all  C-compilers/linkers support direct hunk-chip sections.
  137. Look into the file Box.c how to initialise them on your own.
  138.  
  139. ---------------------------------
  140.  
  141. Sprites:
  142. Until  Kickstart  3.0  a  sprite  had a maximum of 16 pixels in width, up from
  143. this  Kickstart the maximum-width for a sprite has grown to 64 pixels. Because
  144. sprites  have  a  maximum of 4 colours (depth=2 - without tricks!) BitMapSaver
  145. ever  and only takes the first 2 bitplanes for the sprite image, the other are
  146. ignored.
  147.  
  148. ---------------------------------
  149.  
  150. Images:
  151. Images   have  almost  the  same  binary  format  like  bitplanes,  only  that
  152. image-bitplane-data  are combined within one memory block, i.e. the normal and
  153. the select image can only lie after each other in memory:
  154.  
  155. Image: 48 * 32 pixels, 3 bit planes (8 colours)
  156.  
  157.        Thus the normal image is stored first into memory:
  158.        48 / 8 * 32 * 3 = 576 bytes and right after this
  159.                              the select image is stored:
  160.        48 / 8 * 32 * 3 = 576 bytes
  161.        makes a total of 1152 for both images.
  162.  
  163. If  you use a brush with more than one image, you have to reorder the bitplane
  164. format  to  the  image  format  on  your  own;  perhaps  a  future  version of
  165. BitMapSaver should do the work?
  166.  
  167. Taken out of "intuition/intuition.h|i"
  168.  
  169.  STRUCT(URE) Image(,0)
  170.  WORD    ig_LeftEdge    ; starting offset relative to rastport's X offset (normally zero)
  171.  WORD    ig_TopEdge    ; starting offset relative to rastport's Y offset (normally zero)
  172.  WORD    ig_Width    ; width in pixels (must! be word-aligned)
  173.  WORD    ig_Height    ; number of lines (rows)
  174.  WORD    ig_Depth    ; depth (number of planes)
  175.  APTR    ig_ImageData    ; pointer to the actual image data (Chip-RAM)
  176.  BYTE    ig_PlanePick    ; bitmask for "plane(x) has to blit to display"
  177.  BYTE    ig_PlaneOnOff    ; bitmask for plane data all one (1) or all zero (0)
  178.  APTR    ig_NextImage    ; pointer to the next image or nil
  179.  (LABEL    ig_SIZEOF)
  180.  
  181.  
  182. To make pixel-width word-aligned (boundary 16):
  183. C:     width = ((width + 7) & -8);
  184.  
  185. ASM:   move.w   width,d0
  186.        addq.w   #7,d0
  187.        andi.w   #-8,d0
  188.        move.w   d0,width
  189.  
  190.  
  191.  PlanePick = 13 = % 00001101 - means: blit data as plane 0, 2, 3 but not plane 1!
  192.  PlaneOnOff = 0 = % 00000000 - means: clear all data of plane 1
  193. or
  194.  PlaneOnOff = 2 = % 00000010 - means: set all data of plane 1 to one
  195.  
  196. In  this example the image has only 3 bitplanes where the image structure says
  197. there  are  four.  This  means  that the image itself ( ImageData ) has only 3
  198. planes.  So  in  our  example  plane  0,  2  and  3  will  be  blitted  to the
  199. corresponding bitplanes of the RastPort.
  200. If  PlaneOnOff  is  set  to zero, the concerned RastPort area of bitplane 1 is
  201. cleared, or if PlaneOnOff is set to 2, this area data will be set to one.
  202.  
  203. For plain images use:
  204. PlanePick  %00001111 = 15
  205. PlaneOnOff %00000000 =  0
  206.  - means blit plane 0,1,2 and 3 - PlaneOnOff unused.
  207.  
  208. Resume:
  209.  Only  where  PlanePick's  bitplanes  are  set to zero, PlaneOnOff is taken to
  210.  check for set or unset bits.
  211.  
  212.  In  our  example  this  means  in a 16-colour display all 4 bitplanes will be
  213.  blitted  to  the  display, if the display has less colours, only the affected
  214.  bitplanes will be blitted.
  215.  
  216.  But,  if  the display has more colours (e.g. 256) the upper 4 bitplanes which
  217.  are set to zero (%0000 0000 - PlaneOnOff) are cleared in the display.
  218.                    ¯¯¯¯
  219. Example for a 16-colour image:
  220.  
  221.    PlanePick  %00001111 = 15
  222. OR PlaneOnOff %00000000 =  0
  223.                           --
  224.                           15   - OK.
  225.  
  226.    PlanePick  %00001111 = 15
  227. OR PlaneOnOff %00001111 = 15
  228.                           --
  229.                           15   - Also OK.
  230.  
  231.    PlanePick  %00001111 = 15
  232. OR PlaneOnOff %11111111 = 255
  233.                           ---
  234.                           255  - Wrong !!!! - means 256 colours.
  235.  
  236.    PlanePick  %00001111 = 15
  237. OR PlaneOnOff %00010000 = 16
  238.                           --
  239.                           31   - Also wrong !!!! 32 colours.
  240.  
  241. ---------------------------------
  242.  
  243. QUICK:
  244. This  option  is  only  suitable when writing C- or assembler source codes. It
  245. will  allocate  a  buffer  (20  KB)  where the data are written. When now this
  246. buffer  is  full,  the  contents  of it are saved to disk. This gains a lot of
  247. time even if you are writing your data to a fast medium (e.g. RAM DISK).
  248.  
  249. ---------------------------------
  250.  
  251. RAW:
  252. Sometimes  it  is not suitable to generate a source-code for images, e.g. when
  253. the  images are so tall that MBs are needed to include them, e.g. a picture of
  254. 960*724  width and 8 planes will need 2,296,046 bytes of memory in ASCII form.
  255. Instead  of  it  you may include directly the binary image data - here 695,552
  256. bytes.
  257. You  have  to  force  those  converted  data  on  your  own to Chip-memory (if
  258. required);  also you have to create on your own a bitmap-structure (if needed)
  259. and compute each address for the bitplanes.
  260.  
  261. ---------------------------------
  262.  
  263. PEN:
  264. This  option  is  available  when generating source codes ( C or Asm) and when
  265. writing  raw-data. Instead of the output-data format "Bitplanes" it will force
  266. the  data  to  an 8-bit pen array, which can "blitted" to the display (virtual
  267. screen) via:
  268.  
  269.     OS 1.x  and up    SetAPen()/WritePixel()
  270.     OS 2.x  and up    WritePixelArray8()
  271.             WritePixelLine8()
  272.     OS 3.1    and up    WriteChunkyPixels()
  273.  
  274. This  option  is indeed useful if you have installed a 3rd party graphic board
  275. or  -  if  you  are  in  a surround of OS 3 and you want to adjust the pens to
  276. those  of  that  screen.  Even  when  you write games it is easier to use this
  277. format  instead  of  bitplanes to let the background shine through a specified
  278. colour.
  279.  
  280.  
  281. Altough  I know how to decode bitplane colour index' to the true-colour format
  282. I  don't know if I should implement it into BitMapSaver, i.e. I have a written
  283. a  utility  (labelled  Viewer)  that already de- and encodes picture of 24 bit
  284. depth  (including  HAM6  and  HAM8 images) to the true-colour format (RGB). If
  285. you are interested in such a conversion tell me.
  286.  
  287. ---------------------------------
  288.  
  289. CMAP:
  290. Using  this  option  enables  the storing of the 4-bit colour values either in
  291. the ASCII- or binary file.
  292.  
  293. ---------------------------------
  294.  
  295. RGB32:
  296. If  the option "CMAP" was not chosen, this statement (RGB32) has no effect. It
  297. does  only  work  in conjunction with the option "CMAP". If both are set (CMAP
  298. and!  RGB32)  the  colour  table  is stored as 8-bit colour index which can be
  299. directly used by OS 3.x and up function LoadRGB32() or tag-item SA_Colors32.
  300.  
  301. ---------------------------------
  302.  
  303. SEPRIT:
  304. When  you  have chosen the options "RAW" and "CMAP" for one image, the colour-
  305. table  for this file is stored right behind the image data area. When now this
  306. connected  file  is  loaded  into  Chip-memory,  the  RGB-colour table lies in
  307. Chip-memory,  too.  To  avoid this, you may split this file into two; one will
  308. contain  the  image data, the other the colour-data. The keyword to do this is
  309. "SEPRIT".  A  file  with  the suffix ".cmap" is saved in the same directory as
  310. the  file  containing  the  image data, - when your image-file is named with a
  311. suffix, right in front of your suffix a second is stored, e.g.
  312.  
  313. 4> bitmapsaver box.bsh to ram:Box.bin opt cmap raw seprit
  314.  
  315. Result:
  316.  
  317. RAM Disk:Box.bin
  318. RAM Disk:Box-cmap.bin
  319.  
  320. or:
  321.  
  322. 4> bitmapsaver box.bsh to ram:box opt cmap raw seprit
  323.  
  324. Result:
  325.  
  326. RAM Disk:box
  327. RAM Disk:box.cmap
  328.  
  329. ---------------------------------
  330.  
  331. RAWHDR:
  332. RAWHDR  means RAW-HEADER and will allow you to save the important informations
  333. of the image along with the raw-file when option RAW was chosen.
  334.  
  335. The basic structure (header) is 16 bytes in size:
  336.  
  337.  struct RAWHEADER        STRUCTURE RAWHEADER,0
  338. {
  339.     ULONG    ID;            ULONG    rwh_ID
  340.     UWORD    ImageWidth;        UWORD    rwh_ImageWidth
  341.     UWORD    ImageHeight;        UWORD    rwh_ImageHeight
  342.     UBYTE    Depth;            UBYTE    rwh_Depth
  343.     UBYTE    kludgefill_0;        UBYTE    rwh_kludgefill_0
  344.     UWORD    Flags;            UWORD    rwh_Flags
  345.     UWORD    BMWidth;        UWORD    rwh_BMWidth
  346.     UWORD    Colors;            UWORD    rwh_Colors
  347. };                    LABEL    rwh_SIZEOF
  348.  
  349.  
  350. ID    = BMAP for non-interleaved bitmap data
  351. ID    = PARY for pen array data
  352.     ImageWidth    = real image's width, e.g. 17    (0x11)
  353.     ImageHeight    = number of rows, e.g. 15    (0xF)
  354.     Depth        = number of bitplanes, e.g. 3    (0x3)
  355.     kludgefill_0    = (ever) zero
  356.     Flags        = bit 0 set when this raw-data file
  357.               contains a colour map at its end
  358.             = bit 7 set when the colour map is
  359.               stored in the RGB32 format
  360.     BMWidth        = boundary 16 of ImageWidth, 0x11 to 0x20
  361.     Colors        = Number of used colours
  362.  
  363. In  our  example  an  image of 17 * 15 pixel and 3 bitplanes
  364. without a colour map would look like this:
  365.     BMAP 0011 000F 03 00 0000 0020 0008    or
  366.     PARY 0011 000F 03 00 0000 0020 0008
  367.  
  368. When saved along with a colour map it could look like this:
  369.     BMAP 0011 000F 03 00 0001 0020 0008    or
  370.     PARY 0011 000F 03 00 0001 0020 0008
  371.  
  372. When the colour map is in the RGB32 format it would like this:
  373.     BMAP 0011 000F 03 00 0081 0020 0008    or
  374.     PARY 0011 000F 03 00 0081 0020 0008
  375.  
  376. NOTE:
  377.     The BMAP type is ever aligned to a boundary of 16:
  378.     (0x11 + 15) & -16 = 0x20
  379.     In our example (0x20 / 8 * 3) * 0xF = 180 bytes of pure data!
  380.         [ 0x20    = aligned size of 0x11 = number of pixel in one row ]
  381.          [ 8    = 1 byte of memory can hold 8 pixels ]
  382.         [ 3    = three bitplanes ]
  383.         [ 0xF    = 15 rows ]
  384.  
  385.     The PARY type is not! aligned!!!
  386.     0x11 * 0xF = 255 bytes of pure data!
  387.  
  388.     To make the confusion perfect: the colour map can
  389.     lie at an odd offset, in our example at offset
  390.     (255 + 16 =) 271!!!!
  391.  
  392. A good thing is to use DOS-function Read():
  393.  
  394.     Read first 16 bytes of file!
  395.     Check type:
  396.         if BMAP compute length:
  397.             BMWidth / 8 * Depth * ImageHeight
  398.             Read the amount computed data into data-buffer
  399.             Check Flags for colour map
  400.             if 4-bit colour map:
  401.                 Double Colors, since WORDs have been stored
  402.                 (Colors * 2)
  403.                 Read amount computed data into colour-buffer
  404.              if an 8-bit colour map compute:
  405.                 Colors * 3 * 4 + 8
  406.                 (e.g.: 8 colours = 8 * 3 = 24 LONG WORDs
  407.                  24 LONG WORDs * 4 = 96 bytes
  408.                  plus 8 bytes (2 LONG WORDs)
  409.                  makes a total of 104 bytes )
  410.                 Read amount computed data into colour-buffer
  411.          if PARY compute length:
  412.             ImageWidth * ImageHeight
  413.             Read the amount computed data into data-buffer
  414.             Check Flags for colour map
  415.             if 4-bit colour map:
  416.                 Double Colors, since WORDs have been stored
  417.                 (Colors * 2)
  418.                 Read amount computed data into colour-buffer
  419.              if an 8-bit colour map compute:
  420.                 Colors * 3 * 4 + 8
  421.                 (e.g.: 8 colours = 8 * 3 = 24 LONG WORDs
  422.                  24 LONG WORDs * 4 = 96 bytes
  423.                  plus 8 bytes (2 LONG WORDs)
  424.                  makes a total of 104 bytes )
  425.                 Read amount computed data into colour-buffer 
  426. ---------------------------------
  427.  
  428. By the way:
  429. BitMapSaver is a re-entrant code; you may use the command Resident.
  430. Up  from  Workbench  2.1  or  Kickstart 3.0 the dos-errors will appear in your
  431. native-language.
  432.  
  433.  
  434. Copyright:
  435.     BitMapSaver's object file and the source-code are Freeware.
  436.     It's  strictly  forbidden  to spread the source-code of BitMapSaver to
  437.     other public-domain series as those created by Fred Fish.
  438.     It's   allowed   to  upload  the  object  file  and  documentation  of
  439.     BitMapSaver   to  Aminet.  It's  not  allowed  to  enclose  the  Amiga
  440.     load-file   called  BitMapSaver  to  commercial  programs  without  my
  441.     written permission.
  442.  
  443.     Needless  to  say that I can't be held for any errors may happen using
  444.     BitMapSaver.
  445.  
  446.     (C) 1993 - 1996 J.v.d.Loo (ONIX)
  447.  
  448.